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“Any fool can write code that a 
computer can understand. Good 
programmers write code that 
humans can understand.” 


— Martin Fowler © 2020 Philip Koopman 


Coding Style: Understandability 


= Anti-Patterns: “There are two ways of constructing a software 
e “Style doesn’t matter; design: one way Is to make it so simple that 


it passes all the tests” there are obviously no deficiencies and the 


e Code that is clever 
instead of clear 


other way is to make it so complicated that 
there are no obvious deficiencies.’ 
— C.A.R. (Tony) Hoare, 1980 Turing Award Talk 





= Other people must understand your code 
e Peer reviews wont work if nobody can read your code 
— Write code so that others can tell it is obviously correct 
e If others can't understand it, they will inject bugs 
e If its not obviously correct, then it's wrong. 
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| Make Code Easy To Read 


= Consistent formatting i me 


#include 





<sys/time.h> 
#include <X11/XLib. h> 
#include 


our Obfuscated C 
: : : ar ae Winner: 
e Consistent indentation, braces 
@ 


a we eee Sone Simulator 
Templated headers for files and functions 


74.5,1=221 ‘Xe 
are ee Ett: 
int N,q, C, ysp,U; 


Spaces and “()” to avoid precedence confusion reenter atactoed 


r (XSetForeground(e,k=XCreateGC (e,z 
3 scanf("S1FX1f%1F",y +n, wry, 


»8,@),BlackPixel(e,@)) 
y+s)+1; y ++); XSelectInput(e,z= XCreateSimpleWindow(e, 


u(e@,Z,0,8,490, 400, 
9,0,WhitePixel(e,@) ),KeyPressMask); for(XMapWindow(e,z); ; T=sin(O)){ struct timev a G={ @,dt*1e6} 
3 K= cos(j); N=1e4; Mt= H*_; Z=D*K; F+=_*P; r=E*K; Wecos( 0); m=K*W; H=K*T; O+=D*_*F/ K+d/K*E* 
. t f t | sin(j); a=B*T*D-E*wW; 


oe 

XClearWindow(e,z); " t=T*E+ D*B* W; jt=d*_*D-_*F*E; P=w*E*B-T* D; for (o+=(I=D*Wte 

*T*B,E*d/K *B+v+B/K*F*D)*_; p<y; ){ T=p[s]+i; E=c-p[w]; D= n{p]- L; K=D*m-B*T-H*E; if(p inst ak ae 
]== Qe 


K a (W=T*r-I*E +D*P) |fabs(D=t *D+Z *T-a *E)> K)N=1e4; else{ q=W/K *4E2+2e2; C= K 
*D; N-1E4& wiocslanreais Gi Zak, a, a 5 N= “45 alk es } ae ue ra © (X*t +P*M+m*1); T=X*X+ = a *; 
li a ak ,20,380 _3 for(; XPending(e); u *=CS!=N){ 
XEvent aa AextEvent(e , &z re 
= Comments “ee 
= wkey ®))- IT? 


e Explain what & why, not just code paraphrase a 


DN “NP N- oe ?N= 


e Comments are not a design = 
= Naming 


h* *e4/1-(1* 


e Descriptive, consistent naming conventions ‘og 
E.g., variables are nouns; functions are verbs ate 


sprintt(f, 
"%5d = %3d" 


m Avoid magic numbers (use const) gree 


ade sig d+=T*(.45-14/1* 
X-a*130-J* .14)* 2+F* 


ay fi 0 vs Ube CE 
*I-m* 52+E*94 D-t* 8tu*.21*E) /1e2+W* 
179*v)/2312; select(p-2,0,040,86); v-=( 
W*F-T*(.63*m-1I* .086+m*E*19-D* ae bs Ba | 
e Avoid macros (use inline) os 


_3 D=cos(o0); ater Fy 


http://blog.aerojockey.com/post/iocccsim 


© 2020 Philip Koopman 3 


Good Code Hygiene 


m Modularity 
e Many smaller .c/.cpp files (one per class) 
e Externally visible declarations into .h file 
= Conditional Statements 
e Boolean conditional expression results; no assignments 
e All switch statements have a default (usually error trap) 
e Limited nesting (see also cyclomatic complexity) 
= Variables 
e Descriptive names that differ significantly 
e Smallest practicable scope for variables; initialize at point of definition 
e Use typedefs to define narrow types (also use uint32_t, use enum, etc.) 
e Range checks & bounds checks (e.g., buffer overflow) 
m= Handle errors returned by called functions 













oC? eo 


on>>* et 
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Optimization 





"We should forget about small efficiencies, say about 97% of the time: 


premature optimization is the root of all evil. Yet we should 
not pass up our opportunities in that critical 3%" 


e Donald Knuth (December 1974). "Structured Programming 
with go to Statements". ACM Journal Computing Surveys 6 (4): 268. 


= Dont optimize unless you have performance data 
e Most code doesnt matter for speed 
e Use little or no assembly language. Get a better compiler. 


= Optimization makes it hard to know your code is right 
e Do you want correct code or tricky code? 
— (Pick one. Which one is safer?) 
e Buy a bigger CPU if you have to 











ARE YOU PREMATUKELY 
OPTIMIZING OR JUST TAKING 
TIME TODO THINGS RIGHT? 





ARE YOU CONSULTING A 
FLOLCHART To ANSWER 
THIS QUESTION? 







YOU ARE 
PREMATURELY 
OPTIMIZING 


https://xkced.com/1691/ 
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_ Coding Understandability Best Practices 


= Pick a coding style and follow it Great style depends 
e Use tool support for language formatting upon point of view. 
e Evaluate naming as part of peer review 
e Comments are there to explain implementation 


= The point of good style is to avoid bugs 
e Make it hard for a reviewer to miss a problem 
— Even better, make it easy for a tool to find problem 
e Also need to have a good technical style 


= Coding style pitfalls: 
e Optimizing for the author instead of the reviewer 
e Making it too easy to deviate from style rules 
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Does it run? Just leave it alone. 


“Always code as if 





the guy who ends up 
maintaining your code 
will bea 
violent psychopath 
who knows where you live. 
py Code for readability.” 

(su letetea @erelomearl! 
No) bYere hia 0} om Or els Neel (Author unclear) 

The Definitive Guide 
O RLY? @ ThePracticalDev 
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KEEP IN MIND THAT IM .. WOW. IT'S LIKE A SALAD RECIPE | | ITS LIKE SOMEONE TOOK A 
SELF-TAUGHT, SO MY CODE. THIS IS LIKE. BEING IN WRITTEN BY A CORPORATE. | | TRANSCRIPT OF A COUPLE 
MAY BEA LITTLE MESSY. A HOUSE. BUILT BY A LAWYER USING A PHONE | | ARGUING AT IKEA AND MADE 
LEMME SFE- CHILD USING NOTHING AUTOCORRECT THAT ONLY RANDOM EDITS UNTIL IT 
IM SURE BUT A HATCHET AND A KNEW EXCEL FORMULAS, COMPILED WITHOUT ERRORS. 


OKAY, TLL READ 
A —t 


ITS FINE. PICTURE OF A HOUSE. 


REBT | SBE 


https://xkcd.com/1513/ 
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